Array Methods

The Array object contains the following methods:

CxScript.Array Usage Notes

Note the relationship between the Count and UBound properties and the ReDim and Resize methods. Each pair is mutually redundant (Count equals UBound + 1), but each name exists to allow for different styles of programming. In VBScript, ReDim and UBound control the upper index, rather than the size.

For example, to set the size of a 10-element array, use arr.Redim(9) or arr.Resize(10)

Additionally, in CxScript.Array, the ReDim and Resize functions both act like ReDim Preserve in VBScript. There’s no single analog to ReDim without Preserve, but calling Clear and then ReDim will function similarly.

item Property

The item property is the default property, so it does not need to be explicitly named. For example:

1
2
3
4
5
6
7
8
Dim arr : Set arr = CreateObject("CxScript.Array")
 
arr.Add "Bob"
        ' arr now contains one element of type string with a value of Bob
    arr(0) = "Sally"
        ' arr now contains one element of type string with a value of Sally
    WScript.Echo arr(0)
        ' Sally was printed to the screen

get__Enum Method

There’s also a get__Enum method that shouldn’t be explicitly used, but is provided for integration with VBScript’s For Each loop, so these two loops are equivalent:

1
2
3
4
5
6
7
For i = arr.LBound to arr.UBound
    WScript.Echo arr(i)
Next
 
For Each elem in arr
    WScript.Echo elem
Next

Add

The Add method adds an item to the end of the array.

Syntax

Add(ByVal item)

Example

The following example adds the number 805 to the end of the array.

1
2
3
4
Dim objCxArray
    Set objCxArray = CreateObject("CxScript.Array")
 
    objCxArray.Add 805

AddRange

The AddRange method adds the given array to the end of this array.

Syntax

AddRange(ByVal Array)

Example

The following example adds each of the lists of facilities returned by GetFacilityList to the end of the array.

1
2
3
4
5
6
7
8
9
10
11
12
Dim objCxArray, arrCVSs, strCVS, objGlobFunc
    Set objCxArray = CreateObject("CxScript.Array")
    Set objGlobFun = CreateObject("CxScript.GlobalFunctions")
     
    arrCVSs = Array("HSS", "OPCIS", "SVCMON", "UIS")
     
    For each strCVS in arrCVSs
        Dim arrFacs
        objGlobFunc.GetFacilityList "CYGDEMO." & strCVS, arrFacs
     
        objCxArray.AddRange arrFacs
    Next

Clear

The Clear method empties the array, and returns the count back to 0.

Syntax

Clear()

Example

The following example clears the array after displaying the sorted items.

1
2
3
4
5
6
7
8
9
10
11
12
13
Sub SortAndDisplay (arrItems)
    Dim objCxArray, item
    Set objCxArray = CreateObject("CxScript.Array")
     
    objCxArray.AddRange arrItems
    objCxArray.Sort True
     
    For each item in objCxArray
        Wscript.Echo item
    Next
     
        objCxArray.Clear
End Sub

IndexOf

The IndexOf method searches for the specified item and returns the zero-based index of the first occurrence within the entire array. Returns -1 if not found.

Syntax

IndexOf(ByVal item) As Long

Example

The following example checks if the first occurrence of the item in the array matches the last occurrence.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
Function IsItemUnique(arrItems, varItem)
    Dim objCxArray, iFirst, iLast
    Set objCxArray = CreateObject("CxScript.Array")
     
    objCxArray.AddRange arrItems
    iFirst = objCxArray.IndexOf(varItem)
     
    If iFirst <> -1 Then
        iLast = objCxArray.LastIndexOf(varItem)
        If iFirst = iLast Then
            IsItemUnique = True
        Else
            IsItemUnique = False
        End If
    End If
End Function

Join

The Join method concatenates the elements of this array, using the specified separator between each element. The method does not try to "escape" the separator if it exists in any of the elements.

Syntax

Join(ByVal separator As String, [ByVal ignoreFailedElements As Boolean = False]) As String

Example

The following example displays a message box with each array items separated by a carriage return.

1
2
3
4
5
6
7
8
Sub DisplayItems (arrItems)
    Dim objCxArray
    Set objCxArray = CreateObject("CxScript.Array")
     
    objCxArray.AddRange arrItems
     
    MsgBox objCxArray.Join(vbCr)
End Sub

LastIndexOf

The LastIndexOf method searches for the specified item and returns the zero-based index of the last occurrence within the entire array. Returns -1 if not found.

Syntax

LastIndexOf(ByVal item) As Long

Example

The following example checks if the first occurrence of the item in the array matches the last occurrence.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
Function IsItemUnique(arrItems, varItem)
    Dim objCxArray, iFirst, iLast
    Set objCxArray = CreateObject("CxScript.Array")
     
    objCxArray.AddRange arrItems
    iFirst = objCxArray.IndexOf(varItem)
     
    If iFirst <> -1 Then
        iLast = objCxArray.LastIndexOf(varItem)
        If iFirst = iLast Then
            IsItemUnique = True
        Else
            IsItemUnique = False
        End If
    End If
End Function

PrepareToAdd

The PrepareToAdd method hints that Add will be called in a loop. An optimization only, it is not required to call for a correct program.

Syntax

PrepareToAdd(ByVal piSize As Long)

Example

The following example uses PrepareToAdd to hint that 50 items will be added through a looped Add call.

1
2
3
4
5
6
7
8
9
Dim objCxArray, objGlobFunc, iLoop
    Set objCxArray = CreateObject("CxScript.Array")
    Set objGlobFunc = CreateObject("CxScript.GlobalFunctions")
     
    objCxArray.PrepareToAdd 50
     
    For iLoop = 0 to 49
        objCxArray.Add iLoop
    Next

ReDim

The ReDim method resizes the array such that UBound is now equal to the given parameter. Any elements still remaining in the array after the resize will be preserved. ReDim(NewUBound) is equivalent to Resize(NewUBound + 1).

Syntax

ReDim(ByVal Count As Long)

Example

The following example adjusts the size of the array object to 10 indices, preserving the 5 items from the AddRange call.

1
2
3
4
5
Dim objCxArray
Set objCxArray = CreateObject("CxScript.Array")
 
objCxArray.AddRange Array("First", "Second", "Third", "Fourth", "Fifth")
objCxArray.ReDim 9

Remove

The Remove method removes the first occurrence of a specific item from the array.

Syntax

Remove(ByVal item)

Example

The following example removes the "~TEMPLATE" item from the list of facilities returned.

1
2
3
4
5
6
7
8
Dim objCxArray, objGlobFunc, arrFacs
Set objCxArray = CreateObject("CxScript.Array")
Set objGlobFunc = CreateObject("CxScript.GlobalFunctions")
 
objGlobFunc.GetFacilityList "CYGDEMO.SVCMON", arrFacs
 
objCxArray.AddRange arrFacs
objCxArray.Remove "~TEMPLATE"

RemoveAt

The RemoveAt method removes the element at the given index from the array.

Syntax

RemoveAt(ByVal index As Long)

Example

The following example removes the middle entry from the array.

1
2
3
4
5
6
7
8
9
Sub RemoveMid(arrItems)
    Dim objCxArray, iMid
    Set objCxArray = CreateObect("CxScript.Array")
     
    objCxArray.AddRange arrItems
    iMid = CInt((UBound(arrItems)+1)/2)
     
    objCxArray.RemoveAt(iMid)
End Sub

Resize

The Resize method resizes the array such that Count is now equal to the given parameter. Any elements still remaining in the array after the resize will be preserved.

Syntax

Resize(ByVal Count As Long)

Example

The following example adjusts the size of the array object to 3 indices, preserving only the first 3 items from the AddRange call.

1
2
3
4
5
Dim objCxArray
Set objCxArray = CreateObject("CxScript.Array")
 
objCxArray.AddRange Array("First", "Second", "Third", "Fourth", "Fifth")
objCxArray.Resize 3

Sort

The Sort method sorts the items in the array in ascending or descending order.

Syntax

Sort([ByVal bAscending As Boolean = True])

Example

The following example sorts an array, into descending order, and displays the items.

1
2
3
4
5
6
7
8
9
10
11
Sub ReverseSortAndDisplay(arrItems)
    Dim objCxArray, item
    Set objCxArray = CreateObject("CxScript.Array")
     
    objCxArray.AddRange arrItems
    objCxArray.Sort False
     
    For each item in objCxArray
        Wscript.Echo item
    Next
End Sub

ToArray

The ToArray method returns a copy of the array as a VBScript array.

Syntax

ToArray()

Example

The following example sorts and then returns a VBScript array.

1
2
3
4
5
6
7
8
9
Function SortThis(arrInput)
    Dim objCxArray
    Set objCxArray = CreateObject("CxScript.Array")
    objCxArray.AddRange arrInput
     
    objCxArray.Sort True
     
    SortThis = objCxArray.ToArray
End Function